home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / stdlib / RCS / malloc.man,v < prev    next >
Encoding:
Text File  |  1990-09-06  |  3.8 KB  |  179 lines
  1. head     1.2;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    shirriff:1.2; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.2
  10. date     89.12.19.08.18.06;  author ouster;  state Exp;
  11. branches ;
  12. next     1.1;
  13.  
  14. 1.1
  15. date     89.12.19.08.17.08;  author ouster;  state Exp;
  16. branches ;
  17. next     ;
  18.  
  19.  
  20. desc
  21. @@
  22.  
  23.  
  24. 1.2
  25. log
  26. @Don't permit realloc's ptr to refer to free storage.  Don't
  27. promise page-aligned memory for large allocations.
  28. @
  29. text
  30. @.\" Copyright (c) 1980 Regents of the University of California.
  31. .\" All rights reserved.  The Berkeley software License Agreement
  32. .\" specifies the terms and conditions for redistribution.
  33. .\"
  34. .\"    @@(#)malloc.3    6.3 (Berkeley) 5/14/86
  35. .\"
  36. .TH MALLOC 3  "May 14, 1986"
  37. .UC 4
  38. .SH NAME
  39. malloc, free, realloc, calloc, alloca \- memory allocator
  40. .SH SYNOPSIS
  41. .nf
  42. .B char *malloc(size)
  43. .B unsigned size;
  44. .PP
  45. .B free(ptr)
  46. .B char *ptr;
  47. .PP
  48. .B char *realloc(ptr, size)
  49. .B char *ptr;
  50. .B unsigned size;
  51. .PP
  52. .B char *calloc(nelem, elsize)
  53. .B unsigned nelem, elsize;
  54. .PP
  55. .B char *alloca(size)
  56. .B int size;
  57. .fi
  58. .SH DESCRIPTION
  59. .I Malloc
  60. and
  61. .I free
  62. provide a general-purpose memory allocation package.
  63. .I Malloc
  64. returns a pointer to a block of at least
  65. .I size
  66. bytes beginning on a word boundary.
  67. .PP
  68. The argument to
  69. .I free
  70. is a pointer to a block previously allocated by
  71. .IR malloc ;
  72. this space is made available for further allocation,
  73. but its contents are left undisturbed.
  74. .PP
  75. Needless to say, grave disorder will result if the space assigned by
  76. .I malloc
  77. is overrun or if some random number is handed to
  78. .IR free .
  79. .PP
  80. .I Malloc
  81. maintains multiple lists of free blocks according to size,
  82. allocating space from the appropriate list.
  83. It calls
  84. .I sbrk
  85. (see
  86. .IR brk (2))
  87. to get more memory from the system when there is no
  88. suitable space already free.
  89. .PP
  90. .I Realloc
  91. changes the size of the block pointed to by
  92. .I ptr
  93. to
  94. .I size
  95. bytes and returns a pointer to the (possibly moved) block.
  96. The contents will be unchanged up to the lesser of the new and old sizes.
  97. The Sprite version of \fIrealloc\fR differs from other UNIX versions
  98. in that \fIptr\fR may not point to a free block (in other UNIX
  99. versions \fIptr\fr may poin to a block freed since the last call to
  100. \fImalloc\fR, \fIcalloc\fR, or \fIrealloc\fR).
  101. .PP
  102. .I Calloc
  103. allocates space for an array of
  104. .I nelem
  105. elements of size
  106. .I elsize.
  107. The space is initialized to zeros.
  108. .PP
  109. .I Alloca
  110. allocates 
  111. .I size
  112. bytes of space in the stack frame of the caller.
  113. This temporary space is automatically freed on
  114. return.
  115. .PP
  116. Each of the allocation routines returns a pointer
  117. to space suitably aligned (after possible pointer coercion)
  118. for storage of any type of object.
  119. .SH SEE ALSO
  120. brk(2),
  121. pagesize(2)
  122. .SH DIAGNOSTICS
  123. .I Malloc, realloc
  124. and
  125. .I calloc
  126. return a null pointer (0) if there is no available memory or if the arena
  127. has been detectably corrupted by storing outside the bounds of a block.
  128. .I Malloc
  129. may be recompiled to check the arena very stringently on every transaction;
  130. those sites with a source code license may check the source code to see
  131. how this can be done.
  132. .SH BUGS
  133. When
  134. .I realloc
  135. returns 0, the block pointed to by
  136. .I ptr
  137. may be destroyed.
  138. .PP
  139. The current implementation of
  140. .I malloc
  141. does not always fail gracefully when system
  142. memory limits are approached.
  143. It may fail to allocate memory when larger free blocks could be broken
  144. up, or when limits are exceeded because the size is rounded up.
  145. It is optimized for sizes that are powers of two.
  146. .PP
  147. .I Alloca
  148. is machine dependent; its use is discouraged.
  149. @
  150.  
  151.  
  152. 1.1
  153. log
  154. @Initial revision
  155. @
  156. text
  157. @d68 4
  158. a72 15
  159. In order to be compatible with older versions,
  160. .I realloc
  161. also works if
  162. .I ptr
  163. points to a block freed since the last call of
  164. .I malloc, realloc
  165. or
  166. .IR calloc ;
  167. sequences of
  168. .I free, malloc
  169. and
  170. .I realloc
  171. were previously used to attempt storage compaction.
  172. This procedure is no longer recommended.
  173. .PP
  174. a89 3
  175. If the space is of
  176. .I pagesize
  177. or larger, the memory returned will be page-aligned.
  178. @
  179.